IRIX Base Documentation 2001 May

home *** CD-ROM | disk | FTP | other *** search

/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / f90 / fffcntl.z / fffcntl

Wrap

Text File | 1998-10-30 | 23.2 KB | 458 lines

FFFCNTL(3C) Last changed: 2-25-98 NNAAMMEE ffffffccnnttll - Performs functions on files opened using flexible file I/O SSYYNNOOPPSSIISS ##iinncclluuddee <<ffffiioo..hh>> UNICOS and UNICOS/mk systems: iinntt ffffffccnnttll ((iinntt _f_d,, iinntt _c_m_d,, [[,,lloonngg **_a_r_g,, ssttrruucctt ffffssww **_s_t_a_t]]));; IRIX systems: iinntt ffffffccnnttll ((iinntt _f_d,, iinntt _c_m_d,, vvooiidd **_a_r_g,, ssttrruucctt ffffssww **_s_t_a_t));; IIMMPPLLEEMMEENNTTAATTIIOONN UNICOS, UNICOS/mk, and IRIX systems DDEESSCCRRIIPPTTIIOONN The ffffffccnnttll function performs a variety of functions on files opened by ffffooppeenn or ffffooppeennss, using flexible file I/O (FFIO). Arguments are as follows: _f_d Number returned by function ffffooppeenn or ffffooppeennss. _c_m_d Specifies values defined in header file ffffiioo..hh. See under the next heading, VALUES FOR _c_m_d ARGUMENT. _a_r_g The type and value of _a_r_g is _c_m_d specific. See preceding descriptions. _s_t_a_t Pointer to the status return structure. VVaalluueess ffoorr _c_m_d AArrgguummeenntt The following values can be used for the _c_m_d argument introduced above: FFCC__AACCPPTTBBAADD Accepts bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems.) _a_r_g is a pointer to structure ffffcc__bbaaddddaattaa__ss, defined in header file ffffiioo..hh. This _c_m_d is valid with the ttaappee FFIO layer. The fields of this structure have the following meaning: ffffcc__bbyytteess Number of bytes of bad data transferred is returned in this field. ffffcc__mmaaxxffllaagg Set this value to 1 if a maximum value is specified in field ffffcc__mmaaxxwwoorrddss. Set this value to 0 if no maximum value is specified. ffffcc__mmaaxxwwoorrddss Maximum number of words of bad data to transfer to user's data area. If the number of words of bad data in the block exceed this value, the excess is discarded. ffffcc__tteerrmmccnndd Position after accepting bad data is shown in this field, as follows: 0 indicates end of block; 1 indicates EEOOFF; 2 indicates EEOODD; and a value less than 0 indicates that an error occurred. The absolute value is the error number. ffffcc__uuddaa User data area to receive bad data. FFCC__AASSPPOOLLLL Checks for completion of an asynchronous FFIO request. Argument _a_r_g is a pointer to a structure of type ssttrruucctt ffffssww, which had previously been passed to an asynchronous FFIO request. The purpose of this call is to pass control to the underlying layers to do intermediate processing or cleanup on the request. If the request is complete, fields in the status return structure are set as described under function ffffrreeaaddaa(3C). FFCC__CCHHEECCKKTTPP Checks tape position. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is a pointer to structure ffffcc__cchhkkttpp__ss, defined in header file ffffiioo..hh. This command is valid with the ttaappee FFIO layer. The fields of this structure have the following meaning: _s_t_a_t The status of the tape, as follows: -1 = No status 0 = At EOV 1 = Tape off reel 2 = Tape mark detected 3 = Blank tape detected The remaining fields are unused. FFCC__EENNDDSSPP Ends special processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is unused. This function removes the alternate path to tape created by FFCC__SSTTAARRTTSSPP. Tape blocks that were held aside are written to tape. This _c_m_d is valid with the ttaappee FFIO layer. FFCC__CCLLOOSSEEVV Closes volume and mounts next volume in the Volume Identifier list. _a_r_g is unused. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. The eerr9900 layer is not supported on CRAY T3E systems. This _c_m_d is valid with the following FFIO layers: ttaappee, eerr9900, bbuuffaa. FFCC__GGEETTTTPP Retrieves information about an opened tape file (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is a pointer to structure ffffcc__ggeettttpp__ss, defined in header file ffffiioo..hh. The eerr9900 layer does not guarantee that records correspond to physical tape blocks. See the aassssiiggnn(1) man page and the _T_a_p_e _S_u_b_s_y_s_t_e_m _U_s_e_r'_s _G_u_i_d_e, publication SG-2051 for more information about the eerr9900 FFIO layer. The fields of this structure have the following meaning: ffffcc__gglleenn Number of words to copy to the array pointed to by field ffffcc__ppaa. ffffcc__ssyynncchh Synchronization value, as follows: a value of 11 indicates to synchronize the dataset before obtaining position information; a value of 00 means do not synchronize the dataset. This field is ignored if the last operation was a read. It is also invalid to specify this value if end-of-volume (EEOOVV) processing is enabled, and the user has reached EEOOVV but has not started special processing. ffffcc__ppaa Address of array that will contain information returned by this function. The values returned in this array are as follows: ffffcc__ppaa[[00]] Current volume identifier. ffffcc__ppaa[[11]] - ffffcc__ppaa[[66]] Characters 1-48 of the path name of the file opened to this tape. ffffcc__ppaa[[77]] Integer file section number. ffffcc__ppaa[[88]] Integer file sequence number. ffffcc__ppaa[[99]] Integer block number relative to tape mark specified in ffffcc__ppaa[[2222]]. ffffcc__ppaa[[1100]] Integer number of blocks in the library buffer. If additional processing layers have been specified with aassssiiggnn(1) or aassggccmmdd(1), those layers may also hold buffered data, but they will not be included in this field. ffffcc__ppaa[[1111]] Integer number of blocks in the IOP or system buffer. ffffcc__ppaa[[1122]] Integer device ID or unit number. ffffcc__ppaa[[1133]] Device identifier or name. ffffcc__ppaa[[1144]] Generic device name. ffffcc__ppaa[[1155]] Last device function. ffffcc__ppaa[[1166]] Last device status. ffffcc__ppaa[[1177]] Data transfer count in bytes. ffffcc__ppaa[[1188]] Buffer memory sector count. ffffcc__ppaa[[1199]] Partial block bytes in buffer memory. ffffcc__ppaa[[2200]] Outstanding sector count. ffffcc__ppaa[[2211]] Outstanding block count. ffffcc__ppaa[[2222]] User tape mark number, including tape marks embedded in the data. ffffcc__ppaa[[2233]] Direction from tape mark in previous word: 0 = after tape mark; 1 = before tape mark. ffffcc__ppaa[[2244]] Today's year modulus 100. ffffcc__ppaa[[2255]] Today's Julian day. ffffcc__ppaa[[2266]] File identifier, up to the first 8 characters. ffffcc__ppaa[[2277]] Record format name. ffffcc__ppaa[[2288]] Tape density: 1 = 1600 bpi; 2 = 6250 bpi. ffffcc__ppaa[[2299]] Maximum block size. ffffcc__ppaa[[3300]] Record length. ffffcc__ppaa[[3311]] File status: 1 = new; 2 = old; 3 = append. ffffcc__ppaa[[3322]] Label type: 1 = no label; 2 = ANSI label; 3 = IBM standard label; 4 = bypass label. ffffcc__ppaa[[3333]] Integer file sequence number of first file on volume. ffffcc__ppaa[[3344]] Ring status: 0 = ring out; 1 = ring in. ffffcc__ppaa[[3355]] Expiration year modulus 100. ffffcc__ppaa[[3366]] Expiration Julian day. ffffcc__ppaa[[3377]] First volume identifier of file. ffffcc__ppaa[[3388]] User end-of-volume status: 0 = EOV processing off; 1 = EOV processing on. ffffcc__ppaa[[3399]] User end-of-volume processing status: 0 = not in active EOV processing; 1 = in active EOV processing. ffffcc__ppaa[[4400]] User read/write tape mark status: 0 = user read/write tape mark not allowed; 1 = user read/write tape mark is allowed. ffffcc__ppaa[[4411]] Block attribute: ''BB'' = blocked records; ''SS'' = spanned records, if the record format is ''VV'', or standard records, if the record format is ''FF''; ''RR'' = blocked and spanned records, if the record format is ''VV'', blocked and standard records, if the record format is ''FF''; ''00'' = none of the previous values. ffffcc__ppaa[[4422]] - ffffcc__ppaa[[4477]] File identifier. FFCC__GGEETTIINNFFOO Gets information about the layers connected to this open file. _a_r_g is a pointer to structure ffffcc__iinnffoo__ss. The information returned in this structure is as follows: ffffcc__ffllaaggss Flag word containing attributes of the file/connection. These bit masks are defined in header file ffffiioo..hh and are set if true, as follows: FFFFCC__SSTTRRMM Can handle stream I/O. FFFFCC__RREECC Can handle records. FFFFCC__WWEEOOFF Can represent EEOOFF. FFFFCC__WWEEOODD Can represent EEOODD (always set). FFFFCC__BBKKSSPP Can handle backspace. FFFFCC__BBKKFFIILL Can handle backfile. FFFFCC__SSEEEEKKAA Can seek absolute. FFFFCC__SSEEEEKKRR Can seek relative. FFFFCC__SSEEEEKKEE Can seek to end. FFFFCC__PPOOSSRREECC Can position by record number. FFFFCC__PPOOSSFFIILL Can position by EEOOFF mark. FFFFCC__RRWWNNDD Can rewind by seek(x,0,0). FFFFCC__FFIIXXDD Can do fixed-length records. FFFFCC__VVAARR Can do variable-length records. FFFFCC__BBIINNAARRYY Can do binary data. FFFFCC__CCOODDEEDD Can do formatted (character) data. FFFFCC__RRDDMM Can do random I/O (no truncation). FFFFCC__SSEEQQ Can do sequential I/O. FFFFCC__AASSYYNNCC Can do asynchronous I/O. (All layers have asynchronous entry points, but this bit tells whether the behavior is actually async.) FFFFCC__WWRRTTRRUUNNCC Write implies truncation. FFFFCC__NNOOTTRRNN Does no transformation on data; no control words are added or subtracted. Data is not changed. ffffcc__ggrraann Minimum granularity. This is the smallest size in bits of a valid data transfer. For example, the system call layer has an ffffcc__ggrraann of 8, as it can handle a byte as its smallest unit of data transfer. Some CDC record formats have a granularity of 60. ffffcc__rreecclleenn Valid only for fixed length records. This is the record length in bits. ffffcc__ffdd Lowest level file descriptor for the layer that makes system calls. This is not always available, or may not be meaningful for some layers or combinations of layers. This is -1 if no descriptor is available. FFCC__GGEETTLLKK Performs an ffccnnttll call with _c_m_d FF__GGEETTLLKK. _a_r_g is a pointer to structure fflloocckk (defined in ssyyss//ffccnnttll..hh), which is used in the ffccnnttll call. Currently supported only by the ssyyssccaallll and ssyysstteemm layers, and not for tapes or ER90 devices. FFCC__GGEETTLLKKWW Performs an ffccnnttll call with _c_m_d FF__GGEETTLLKKWW. _a_r_g is a pointer to structure fflloocckk (defined in ssyyss//ffccnnttll..hh), which is used in the ffccnnttll call. Currently supported only by the ssyyssccaallll and ssyysstteemm layers, and not for tapes or ER90 devices. FFCC__IIAALLLLOOCC Performs an iiaalllloocc system call. Supported only on UNICOS and UNICOS/mk architectures and only by the ssyyssccaallll and ssyysstteemm layers. Not supported for tapes or ER90 devices. _a_r_g is a pointer to structure ffff__iiaalllloocc__ssttrruucctt, defined in the ffffiioo..hh file. The iiaalllloocc call is made using the following parameters: * The iiaa__nnbb element of the structure is the second argument * The iiaa__ffllaagg element of the structure is the third argument * The iiaa__ppaarrtt element of the structure is the fourth argument * The iiaa__aavvll element of the structure is the fifth argument FFCC__RREECCAALLLL Awaits completion of an asynchronous FFIO request. Argument _a_r_g is a pointer to a structure of type ssttrruucctt ffffssww, which is the status return structure of the asynchronous request. Function ffffffccnnttll waits for completion of the asynchronous request, if necessary. Fields in the status return structure are set as described under function ffffrreeaaddaa(3C). FFCC__SSCCRRAATTCCHH Specifies that a file is to be deleted at close time. The _a_r_g argument is a pointer to _i_n_t. On exit, **_a_r_g is set to contain zero or more of the following result bits: SSCCRR__NNOOFFLLUUSSHH Set if ffffcclloossee processing has been optimized to suppress buffer flushing. SSCCRR__SSIINNGGLLEELLIINNKK Set if the file is not a pipe or a tty, has a link count equal to one, and is not a symbolicly linked file. SSCCRR__UUNNLLIINNKKEEDD Set if this ffffffccnnttll call has successfully unlinked the file. FFCC__SSEETTLLKK Performs an ffccnnttll call with _c_m_d FF__SSEETTLLKK. _a_r_g is a pointer to structure fflloocckk (defined in ssyyss//ffccnnttll..hh), which is used in the ffccnnttll call. Currently supported only by the ssyyssccaallll and ssyysstteemm layers, and not for tapes or ER90 devices. FFCC__SSKKIIPPBBAADD Skips bad data (valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is a pointer to structure ffffcc__bbaaddddaattaa__ss, defined in header file ffffiioo..hh. This _c_m_d is valid with the ttaappee FFIO layer. The fields of this structure used by FFCC__SSKKIIPPBBAADD are as follows; all other fields are unused: ffffcc__bblloocckkss The number of blocks skipped is returned in this field. ffffcc__tteerrmmccnndd Position after skipping bad data is returned in this field, as follows: 0 indicates end of block; 1 indicates EEOOFF or EEOODD; and a value less than 0 indicates that an error occurred. The absolute value is the error number. FFCC__SSTTAATT Returns a structure much like the one returned by the ffssttaatt (see ssttaatt(2)) system call. _a_r_g is a pointer to a ffffcc__ssttaatt__ss structure (from ffffiioo..hh). Fields in this structure are filled in as appropriate by the layers. For the system call layer, all fields are simply retrieved by doing an ffssttaatt call. For other layers, such as mmrr, the _s_i_z_e field in the ssttaatt structure is modified to reflect the buffered data. Other layers can make similar changes to the basic information from the system for similar reasons. The result is a ssttaatt structure that can be used in the same way and for the same purposes as the ffssttaatt system call. FFCC__SSEETTSSPP Disables special EOV processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is an integer value that should be set to 0. See ffffsseettsspp(3C) for a description of how to enable special EOV processing. This _c_m_d is valid with the ttaappee FFIO layers. FFCC__SSTTAARRTTSSPP Starts special EOV processing. This value is valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. _a_r_g is unused. EOV processing must be enabled prior to starting special EOV processing. This function creates an alternative path to or from a tape. Tape blocks in the pipeline are held aside. Subsequent write operations will go directly to tape; subsequent read operations will come directly from tape (if data is available) or from the blocks in the pipeline. Both read and write operations are performed in FIFO order. After you have read from the blocks in the pipeline, they are unavailable for writing. This _c_m_d is valid with the following ttaappee FFIO layer. FFCC__TTPPCC__SSDDBBSSZZ Changes the data block size on an ER90 device. This is valid only when using the ttaappee layer. _a_r_g is the requested new block size. This _c_m_d has no effect when it is used with an IBM- compatible tape. Not supported on IRIX systems. FFCC__TTSSYYNNCC (Valid only for online tape files on UNICOS and UNICOS/mk systems and ER90 files on UNICOS systems. It requests that the tape file be synchronized. This command is ignored if the last operation was a read. It is also invalid to request synchronization if the end-of-volume (EOV) processing is enabled, and the user has reached EOV but has not started special processing. If the end-of-volume processing is enabled, the user should check to see if EOV was reached after requesting FFCC__TTSSYYNNCC (see the description for FFCC__CCHHEECCKKTTPP). In this case, the ffffffccnnttll returns without error, but the tape may not be synchronized (that is, data may remain buffered). This _c_m_d is valid with the following FFIO layers: ttaappee, eerr9900, bbuuffaa. The eerr9900 layer is not supported on CRAY T3E systems. RREETTUURRNN VVAALLUUEESS The ffffffccnnttll function returns 0 on success. Otherwise, it returns -1 and the ssww__eerrrroorr field of the ssttaatt structure contains the error number. SSEEEE AALLSSOO fffflliissttiioo(3C) ffffooppeenn(3C), ffffrreeaaddaa(3C), ffffsseettsspp(3C), ffffwwrriitteeaa(3C) aassssiiggnn(1), aassggccmmdd(1) _T_a_p_e _S_u_b_s_y_s_t_e_m _U_s_e_r'_s _G_u_i_d_e, publication SG-2051, for more information about the eerr9900 FFIO layer _A_p_p_l_i_c_a_t_i_o_n _P_r_o_g_r_a_m_m_e_r'_s _L_i_b_r_a_r_y _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, publication SR-2165, for the printed version of this man page.